Documentation for WINDOW.LIB ============================ Last Update : 112887- DLM Modified/New in this release: Turbo C port Aztec-like 'scr' functions get_ansi_sequence() - bug fix relocate_window() move_window() change_border() remove_title() keyboard_handler() Turbo C only window_mover() " " sys_move_window() " " sys_move_help() " " sys_show_coords() " " Placed system into Public Domain w/complete source. (weren't you sick of "Shareware"?!) ------------------------------------------------------------------------ move_window(direction,count) int direction,count; direction - direction to move window (UP/DN/LF/RT - see window.h) count - must always be 1 in this release. Other values will be supported in future releases. This function moves the current window 1 cursor position in the direction indicated. If the move would position the window partially off the screen the move IS NOT performed. Handles shadowed and unshadowed windows. Nice for smooth scrolling movements. returns - 0 if move was performed. -1 if move could not be performed ------------------------------------------------------------------------- relocate_window(row,col) int row,col; row - target row col - target column This function attempts to move the current window pointed to by the global 'li' to the requested row & col. This guy is VERY fast. return - 0 success. -1 if no window to move. -2 if target coords would cause part of window to be off screen. -------------------------------------------------------------------------- change_border(border_type) int border_type; border_type - 1 of 12 valid border types (see window.h) Changes the border of the window pointed to by 'li' to border_type. Titles are preserved. NOTE: There is a small bug that will trash titles written on a border type of 'blank' or 'none'. This will be fixed in the next release of the sources and library. Until then you can: a) Refrain from using border types 'blank' & 'none' or b) Rewrite the titles after issuing a change_border() call or c) Fix the bug yourself or d) Hate "C", me, and PC's, sell out and buy a Commodore 64 (no drive - cassette tape only!) or maybe a Macinwish! (or is it Macinslop?) ( ... Macinjoke?) returns - nothing -------------------------------------------------------------------------- remove_title(x) int x; x - Either TOP or BOT Removes the top or bottom title of the window pointed to by 'li'. returns - nothing -------------------------------------------------------------------------- window_mover(x) : Only available if compiled w/TURBO C int x; x - Either ON or OFF (see window.h) Enable or disable window mover. If enabled pressing ALT + CTRL will bring up the built-in window mover. The window pointed to by 'li' may be moved about on the screen via the cursor keys. Exit via ESCAPE. returns - ON -mover is on, ALT+CTRL combination is active. OFF -mover is off, ALT+CTRL combination non-active. -------------------------------------------------------------------------- qwritef(row,col,attr,places,decimals,fnum) /* write a float to the screen */ int row,col,attr,places; float fnum; row - row to write numer on col - column to write number at attr - packed attribute to write number with places - specifies number of digits to the left of the decimal place including sign. decimals - specifies the number of digits to the right of the decimal point fnum - a floating point number If fnum cannot be expressed in the field width requested the field will be filled with asterisks. returns - nothing. ------------------------------------------------------------------------ qwrited(row,col,attr,places,decimals,dnum) /* write a double to the screen */ int row,col,attr,places; double dnum; row - row to write number at col - column to write number at. attr - packed attribute to write number with places - specifies number of digits to the left of the decimal point including sign. decimals - specifies the number of digits to the right of the decimal point dnum - a double number . If dnum cannot be expressed in the field width requested the field is filled with asterisks. returns - nothing. ------------------------------------------------------------------------ directory(dir_name,mask) char *dir_name, *mask; *dir_name - pointer to a string containing the full path of the directory to be listed. *mask - pointer to a mask to be used when listing files. Use the global variable 'all_files' if your mask is "*.*". Returns: -1 if path could not be opened/found. 0 if path was valid. dir.key will contain the last key pressed upon exiting the function. dir.indx will contain the index into dir_list[][0] of the last filename chosen. ------------------------------------------------------------------------ init_window(attr) int attr; attr - starting color attribute. Initializes all window system variables. Call this (once) before using any of the other functions in this library. ------------------------------------------------------------------------ make_window(row,col,rows,cols,wattr,battr,border_select) int row - start row of window; int col - start column of window; int rows - number of rows in window; int cols - number of columns in window; int wattr - color attribute inside window frame; int battr - color attribute of window border; int border_select - border type { Make_window() opens a window using the passed parms. The screen area where the window will open is saved. Returns: -1 if cannot allocate anymore windows (30 max). Deallocate some other windows then proceed. -2 if window size/placement is invalid. 0 if window was opened successfully. The global variable "li" will be set on return to point at the structure describing the opened window. ------------------------------------------------------------------------ remove_window() { This function removes the currently opened window (actually the window pointed at by "li") and restores the screen. Also now restores the cursor coordinates. title_window(just,buf,attr,border) int just - justification flag (can be left,right,center) char *buf - pointer to title message to display int attr - color attribute to use int border - flag indicating which border to use (TOP or BOT) Returns: nothing. ------------------------------------------------------------------------ scroll_window(begin,end,dir) int begin - starting row to scroll int end - end row to scroll int dir - direction of scroll (up or down) Returns: nothing. ------------------------------------------------------------------------ title_window(just,buf,attr,border) int just - justification flag; char *buf - pointer to title to write; int attr - color attribute to use; int border - flag indicating where to put title; { This function puts a title on the currently active window. JUST is a flag to indicate how the tile is to be justified. Use the globally defined right,left,and center flags to justify right, left and center. Border is a flag to indicate where to place the title - on the top or bottom borders. Use the globally defined TOP or BOT flags as appropriate. Returns: nothing. ------------------------------------------------------------------------ delay(x) int x - amount of delay This function provides a simple means to generate timed delays. Experiment to find the correct amount of delay by altering the number passed. Returns: nothing. ------------------------------------------------------------------------ ega_check() { This function returns the value of the graphics adapter card installed as found in 0040:0049 on the system var page. A value of 7 is returned if a mono board is installed and currently active. All other values indicate a CGA/EGA board is installed. ------------------------------------------------------------------------ clr_window(color) int color - color attribute of window background; { This function will clear the currently active window using the color attribute passed in color. The character found in the global variable CLEAR_CHAR will be used (defaults to space ). Returns: nothing. ------------------------------------------------------------------------ attr(foreground,background) int foreground - color of foreground; int background - color of background; { This function takes a for/back ground color combination and returns it as a single packed integer. Returns: packed color integer. ------------------------------------------------------------------------ qinit() { This function does first time initilaization of system variables. It is called automatically by the init_window function. If your application does not use windows but you wish to use the other routines in this package you must call this routine first. Returns: nothing. ------------------------------------------------------------------------ qwritelv(row,col,attr,length,str) int row - row to write string; int col - column to write string at; int attr - packed color attribute; int length - length of string to write; char *str - pointer to string to write; { This function writes a string pointed to by str directly to video memory for a length passed in length. This is most useful for writing partial or imbedded strings. Returns: length written. ------------------------------------------------------------------------ qwrite(row,col,attr,str) int row - row to write string on int col - column to write string on; int attr - packed color attribute; char *str - pointer to string; { This function writes null-terminated string directly to video memory at the row and column indicated. Note that the string MUST be null-terminated. Returns: nothing. ------------------------------------------------------------------------ qwritev(row,col,attr,chr) int row - row to write character; int col - column to write character; int attr - packed color attribute; char chr - character to write; { This function writes a single character and attribute directly to video memory at the row & column indicated. Returns: nothing. ------------------------------------------------------------------------ qwritecv(row,coll,colr,attr,str) int row - start row to write string; int coll- left column boundry; int colr - right column boundry; int attr - packed color attribute; char *str - pointer to string to write; { This function writes a null terminated string directly to cideo memory. The string is automagically centered between the left and right boundries passed. Returns: -1 if unsuccessful. 0 if successful. ------------------------------------------------------------------------ qfillc(row,coll,colr,rows,cols,attr,ch) int row - start row; int col - start column; int rows - number of rows to fill; int cols - number of columns to fill; int attr - packed color attribute; char ch - character to write; { This function does repetitive filling of a single character and attribute. The block filled is automagically centered between the column boundries passed. Returns: -1 if unsuccessful. 0 if successful. ------------------------------------------------------------------------ qfill(row,col,rows,cols,attr,ch) int row - start row of fill; int col - start column of fill; int rows - number of row to fill; int cols - number of columns to fill; int attr - packed color attribute; char ch - character to fill; { This function does repetitive fill of a block with a single character and attribute. Returns: nothing. ------------------------------------------------------------------------ qattr(row,col,rows,cols,attr) int row - start row of fill; int col - start column of fill; int rows - number of rows to fill; int cols - number of columns to fill; int attr - packed color attribute; { This function does repetitive filling of an attribute. Useful for changing the color of an area. Returns: nothing. ------------------------------------------------------------------------ qsave(row,col,rows,cols) int row - start row of save; int col - start column of save; int rows - number of rows in area to save; int cols - number of columns in area to save; { This function snapshots the screen and saves it on the heap. This is a low-level primitive and should only be called directly if you good understanding of heap management. Returns: a long 0 if the heap space is exhausted. a long pointer to unsigned char if save was success. This pointer must be saved to release the allocated memory later. ------------------------------------------------------------------------ qrestore() { This function removes the currently active window and restores the screen area that was originally under the window. Returns: nothing. ------------------------------------------------------------------------ get_addr(row,col) int row - row number; int col - column number; { This is a low-level prim that takes a row/column and returns the absolute offset into the screen matrix. Returns: integer offset. ------------------------------------------------------------------------ qbox(row,col,rows,cols,wattr,battr,border_type); int row - start row of box; int col - start column of box; int rows - number of rows in box (including border); int cols - number of columns in box (including border); int wattr - packed color attribute of window area; int battr - packed color attribute of borders; int border_type - type of border to use (0 - 11) { This function builds a box on the screen using the coords and sizes passed. This routine does not preserve the area under the box first. Twelve possible border types are now implemented (see window.h) Returns: nothing. ------------------------------------------------------------------------ change_wcolor(window,border) int window - packed color attribute of window area; int border - packed color attribute of borders; { This function changes the color of an entire window using the parms passed. If the window has a border type of "none" the entire window area will be colored with the 'window' attribute. Returns: nothing. ------------------------------------------------------------------------ cursor(x) int x - on/off flag; { This function turns the cursor on or off. Use the globally defined ON & OFF flags with this function. Returns: nothing. ------------------------------------------------------------------------ get_ansi_color(color) int color - packed color attribute; { This function takes a packed foreground/background attribute and generates the full ANSI escape sequence necessary to change the system for/back ground colors. AZTEC's "scr" functions do not modify the system attributes since these are maintained/changed within the ANSI.SYS driver code. There are ways to locate the driver and do absolute writes to the driver block, but this is a simpler and more portable approach. On return the complete string is in ansi_seq[] and may be printed using the standard C printf() routine. ------------------------------------------------------------------------ ----------------end-of-author's-documentation--------------- Software Library Information: This disk copy provided as a service of The Public (Software) Library We are not the authors of this program, nor are we associated with the author in any way other than as a distributor of the program in accordance with the author's terms of distribution. Please direct shareware payments and specific questions about this program to the author of the program, whose name appears elsewhere in this documentation. If you have trouble getting in touch with the author, we will do whatever we can to help you with your questions. All programs have been tested and do run. To report problems, please use the form that is in the file PROBLEM.DOC on many of our disks or in other written for- mat with screen printouts, if possible. The P(s)L cannot de- bug programs over the telephone. Disks in the P(s)L are updated monthly, so if you did not get this disk directly from the P(s)L, you should be aware that the files in this set may no longer be the current versions. For a copy of the latest monthly software library newsletter and a list of the 1,000+ disks in the library, call or write The Public (Software) Library P.O.Box 35705 - F Houston, TX 77235-5705 (713) 665-7017